Up: @{"Parameters " LINK termcap-Parameters} Next: @{"Using_Parameters" LINK termcap-Using_Parameters} Prev: @{"Encode_Parameters" LINK termcap-Encode_Parameters}
Sending Display Commands with Parameters
----------------------------------------
The termcap library functions `tparam' and `tgoto' serve as the
analog of `printf' for terminal string parameters. The newer
function `tparam' is a GNU extension, more general but missing from
Unix termcap. The original parameter-encoding function is `tgoto',
which is preferable for cursor motion.
* Menu:
@{"tparam" LINK termcap-tparam} The general case, for GNU termcap only.
@{"tgoto" LINK termcap-tgoto} The special case of cursor motion.
@endnode
@node termcap-tparam "termcap-tparam"
Up: @{"Using_Parameters" LINK termcap-Using_Parameters} Next: @{"tgoto " LINK termcap-tgoto} Prev: @{"Using_Parameters" LINK termcap-Using_Parameters}
`tparam'
........
The function `tparam' can encode display commands with any number of
parameters and allows you to specify the buffer space. It is the
preferred function for encoding parameters for all but the `cm'
capability. Its ANSI C declaration is as follows:
char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
The arguments are a control string CTLSTRING (the value of a terminal
capability, presumably), an output buffer BUFFER and SIZE, and any
number of integer parameters to be encoded. The effect of `tparam'
is to copy the control string into the buffer, encoding parameters
according to the `%' sequences in the control string.
You describe the output buffer by its address, BUFFER, and its size
in bytes, SIZE. If the buffer is not big enough for the data to be
stored in it, `tparam' calls `malloc' to get a larger buffer. In
either case, `tparam' returns the address of the buffer it ultimately
uses. If the value equals BUFFER, your original buffer was used.
Otherwise, a new buffer was allocated, and you must free it after you
are done with printing the results. If you pass zero for SIZE and
BUFFER, `tparam' always allocates the space with `malloc'.
All capabilities that require parameters also have the ability to
specify padding, so you should use `tputs' to output the string
produced by `tparam'. @{"Padding" LINK termcap-Padding} Here is an example.
{
char *buf;
char buffer[40];
buf = tparam (command, buffer, 40, parm);
tputs (buf, 1, fputchar);
if (buf != buffer)
free (buf);
}
If a parameter whose value is zero is encoded with `%.'-style
encoding, the result is a null character, which will confuse `tputs'.
This would be a serious problem, but luckily `%.' encoding is used
only by a few old models of terminal, and only for the `cm'
capability. To solve the problem, use `tgoto' rather than `tparam'
to encode the `cm' capability.
@endnode
@node termcap-tgoto "termcap-tgoto"
Up: @{"Using_Parameters" LINK termcap-Using_Parameters} Next: @{"tgoto " LINK termcap-tgoto} Prev: @{"tparam " LINK termcap-tparam}
`tgoto'
.......
The special case of cursor motion is handled by `tgoto'. There are
two reasons why you might choose to use `tgoto':
* For Unix compatibility, because Unix termcap does not have
`tparam'.
* For the `cm' capability, since `tgoto' has a special feature to
avoid problems with null characters, tabs and newlines on
certain old terminal types that use `%.' encoding for that
capability.
Here is how `tgoto' might be declared in ANSI C:
char *tgoto (char *CSTRING, int HPOS, int VPOS)
There are three arguments, the terminal description's `cm' string and
the two cursor position numbers; `tgoto' computes the parametrized
string in an internal static buffer and returns the address of that
buffer. The next time you use `tgoto' the same buffer will be reused.
Parameters encoded with `%.' encoding can generate null characters,
tabs or newlines. These might cause trouble: the null character
because `tputs' would think that was the end of the string, the tab
because the kernel or other software might expand it into spaces, and
the newline becaue the kernel might add a carriage-return, or padding
characters normally used for a newline. To prevent such problems,
`tgoto' is careful to avoid these characters. Here is how this
works: if the target cursor position value is such as to cause a
problem (that is to say, zero, nine or ten), `tgoto' increments it by
one, then compensates by appending a string to move the cursor back
or up one position.
The compensation strings to use for moving back or up are found in
global variables named `BC' and `UP'. These are actual external C
variables with upper case names; they are declared `char *'. It is
up to you to store suitable values in them, normally obtained from
the `le' and `up' terminal capabilities in the terminal description
with `tgetstr'. Alternatively, if these two variables are both zero,
the feature of avoiding nulls, tabs and newlines is turned off.
It is safe to use `tgoto' for commands other than `cm' only if you
have stored zero in `BC' and `UP'.
Note that `tgoto' reverses the order of its operands: the horizontal
position comes before the vertical position in the arguments to
`tgoto', even though the vertical position comes before the
horizontal in the parameters of the `cm' string. If you use `tgoto'
with a command such as `AL' that takes one parameter, you must pass
the parameter to `tgoto' as the "vertical position".
@endnode
@node termcap-Data_Base "termcap-Data_Base"
Up: @{"Top " LINK termcap-Top} Next: @{"Capabilities" LINK termcap-Capabilities} Prev: @{"Library " LINK termcap-Library}
The Format of the Data Base
***************************
The termcap data base of terminal descriptions is stored in the file
`/etc/termcap'. It contains terminal descriptions, blank lines, and
comments.
A terminal description starts with one or more names for the terminal
type. The information in the description is a series of "capability
names" and values. The capability names have standard meanings
(*note Capabilities::.) and their values describe the terminal.
* Menu:
@{"Format" LINK termcap-Format} Overall format of a terminal description.
@{"Capability_Format" LINK termcap-Capability_Format} Format of capabilities within a description.
@{"Naming" LINK termcap-Naming} Naming conventions for terminal types.
@{"Inheriting" LINK termcap-Inheriting} Inheriting part of a description from
a related terminal type.
@endnode
@node termcap-Format "termcap-Format"
Up: @{"Data_Base " LINK termcap-Data_Base} Next: @{"Capability_Format" LINK termcap-Capability_Format} Prev: @{"Data_Base " LINK termcap-Data_Base}
Terminal Description Format
===========================
Aside from comments (lines starting with `#', which are ignored),
each nonblank line in the termcap data base is a terminal description.
A terminal description is nominally a single line, but it can be
split into multiple lines by inserting the two characters `\ newline'.
This sequence is ignored wherever it appears in a description.
The preferred way to split the description is between capabilities:
insert the four characters `: \ newline tab' immediately before any
colon. This allows each sub-line to start with some indentation.
This works because, after the `\ newline' are ignored, the result is
`: tab :'; the first colon ends the preceding capability and the
second colon starts the next capability. If you split with `\
newline' alone, you may not add any indentation after them.
(.txt)